MacWorld UK 2000 March/MW_UK_2000_03.iso/Shareware World/Utilities/Text Processing/Alpha/Help/Alpha Manual

Text File | 1999-07-26 | 107.6 KB | 2,292 lines | [TEXT/ALFA]

        Copyright © 1990-1998 Pete Keleher. All Rights Reserved
        The Tcl code is copyright its respective authors

        Please note: The manual is currently being updated. This
        document is about 90% finished. Other parts of the documentation
        still need a major overhaul.

Legal notice
The Author(s) of this product are in no way liable for any direct or
indirect damage caused by the product.

You may freely copy and distribute Alpha, but please bear in mind that
Alpha is Shareware.  If you decide to keep it, please register your copy
by selecting 'Register' from the 'About…' dialog.

        Introduction

Alpha is a very powerful, multi-purpose text editor.

Alpha is multi-modal, which means it switches between different modes
depending on which type of document you are editing. Everybody who has used
Emacs knows about this concept. The idea with different modes is to change
Alpha's behavior depending on which kind of text you're editing. For
example if you're programming in C++ or editing a LaTeX document you want
different features.

Alpha is very customizable. Much of Alpha's functionality is implemented in
'packages' or 'extensions'. The 'Config->Preferences->Menus And Features'
and 'Config->Mode Prefs->Menus and Features' menu items let you see which
items are installed, and lets you turn them on and off.

Alpha uses Dr. Ousterhout's Tool Command Language (Tcl) as an extension
language. Many of the functions bound to keystrokes, as well as many of the
functions in the menus, are written in Tcl. All the 'packages' or
'extensions' just mentioned are all written in Tcl. Anybody who wants can
write new packages for Alpha!

Of course, you don't have to learn Tcl to use Alpha. You can have lots of
use of Alpha without knowing anything about Tcl. But if you want to become
a real power user, you should consider trying it out. Then the
possibilities of customizing Alpha are unlimited.

How to navigate the documention?

You can quickly jump between different sections of the manual by using the
menu you find under the M icon at the right top of this window.

Also, Alpha supports a limited form of hypertext. Clicking on green
underlined text executes a command associated with the underlined text,
usually taking you to other documentation. Control-<period> will bring you
back.

Alpha contains source from many places, but in particular I'm grateful to
Ray Johnson and Tim Endres for their working on porting TCL to the mac, and
to Tom Scavo and Tom Pollard for their Tcl code contributions. The
following people have also provided considerable code and/or help debugging
the one or two bugs Alpha has had: Masatsugu Nagata, Karl J. Smith, Eric
Sink, David C. Black, Richard T. Austin, Henry Spencer, Vince Darley, Johan
Linde, Tom Fetherston, Jon Guyer and Jerry Fowler.


        Basic editing

The very basics for editing text with Alpha is the same as in any other
Mac application, but Alpha has a number of key shortcuts to speed up your
work, and a couple of features not found in similar applications.
Emacs user will also be happy to know that many of the basic keybindings
used in Emacs are supported by Alpha. However, this requires that you
switch on the Emacs package. Read more in the file Emacs Help.

Moving the Cursor
left-arrow                      backward character
right-arrow                     forward character
up-arrow                        previous-line
down-arrow                      next-line

option-left-arrow               backward one word
option-right-arrow              forward one word

command-left-arrow              beginning of line
command-right-arrow             end of line
command-up-arrow  or  'home'    beginning of window
command-down-arrow  or  'end'   end of window

'Page up'                       move one page backward
'Page down'                     move one page forward

Selecting Text
shift-left-arrow                extend selection one char left
shift-right-arrow               extend selection one char right

shift-up-arrow                  extend selection one line up
shift-down-arrow                extend selection one line down

shift-option-left-arrow         extend selection one word left
shift-option-right-arrow        extend selection one word right

control-h                       select next word

shift-command-left-arrow        select to beginning of line
shift-command-right-arrow       select to end of line

command-B                       select smallest set of parentheses, braces, or
(Balance in Text menu)          brackets that encloses the current selection

double-clicking                 select a word
triple-clicking                 select a line

Control-double-clicking on any type of parentheses or bracket selects from
the parentheses or bracket to its mate. Without the control key held down,
only the intervening text is selected.

Twiddle, Shifting Text
The following functions are found in the Text menu.
Twiddle (command-`)                  Exchange characters bracketing
                                     the selection point.
Twiddle Words (command-option-`)     Exchange words bracketing the
                                     selection point.

Shift Left (command-[)               Shift selection left one tab.
Shift Left Space (command-option-[)  Shift selection left one space.
Shift Right (command-])              Shift selection right one tab.
Shift Right Space (command-option-]) Shift selection right one space.

Drag and Drop editing
Alpha supports drag and drop cut, copy, clear, and paste. To use this
feature, select some text, then move the cursor over the selected text.
The cursor should then turn into an open hand. Mouse down, and move the
cursor to the place you wish to paste the text. When the mouse is
released, the hilighted text is moved to the new location.

Option-mouse does a "copy" instead. You can also drag selections between
windows and to and from other applications, including the Finder. Text
dragged to the Finder is saved in a text clip file. Text can be deleted by
dragging it to the trash can.

You can also drag any text file to an Alpha window to insert the content
of the file in the window.

You MUST have system 7.5 or above or Apple's "Macintosh Drag And Drop"
extension installed. Get a copy from Apple or via Alpha's web page.

Rectangular Editing
If the option key is pressed while the mouse is dragged, a rectangular
section of text is selected instead of the normal selection. This
rectangular selection may extend over multiple lines, but contains only
text between the column of the drag start and the column of the drag end.
The drag cannot end on a column or row less than the start. This selection
can be extended by option-shift-mouse, but not dragged further.

The rectangular selection can be deleted, copied, and pasted. This is very
useful for tables and arrays, such as in LaTeX. Usually, the operation will
be intuitive. However, if you use proportional fonts the selection may
appear ragged. If some of the line contain tabs, the result may not be want
you want. Converting tabs to spaces in the desired region before attempting
rectangular selection usually fixes the problems.

Fill Routines

The 'fill' and 'wrap' routines reformat text to specified line lengths.
This is useful in two case. First, word processors such as Microsoft Word
only insert carriage returns at the end of paragraphs. Secondly, while
typing and inserting text into pre-existing paragraphs, the line lengths
become unequal.

The 'wrap' routine handles word processor documents quickly by merely
inserting carriage returns as necessary to ensure all lines in the selected
region are shorter than specified by the preference 'Fill Column'. Alpha
asks the user if wrapping should be done whenever the user opens files that
have lines longer than 'Para Column' characters. This feature can be
defeated by including the word 'nowrap' anywhere on the first line.

The 'fill' routine goes further. Not only does it break lines, but it also
coalesces lines to eliminate short lines. The routine works by stripping
the relevant text of white space, then re-inserting white space and
carriage returns so that no line extends past 'Fill Column' characters in
length and begins with 'Left Fill Column' spaces characters.

The preferences 'Fill Column', 'Para Column', and 'Left Fill Column' can
all be set in the dialog "Config->Preferences->Text".

Both the fill and wrap routines come in two flavors, 'Fill/Wrap Paragraph'
and 'Fill/Wrap Region'.

Fill Paragraph
If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the paragraph surrounding the insertion point. The
definition of a 'paragraph' may be mode dependent, but in Text mode it is
the text between the closest empty lines. Fill Paragraph also uses an extra
preference 'Double Spaces', which determines if an extra space after should
be placed after the '.' at the end of each sentence. This preference is set
in the dialog "Config->Preferences->Text".
Fill Region
If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the region between the insertion point and the mark.
Wrap Paragraph
Wrap the paragraph surrounding the insertion point.
Wrap Region
If there's a selection, then wrap the selection. If not then wrap the
region between the insertion point and the mark.

        User interface details

Alpha's interface has several non-standard features, which are described in
this section.

Horizontal scrollbar
You can remove the horizontal scrollbar from Alpha's windows in order to
give you more real estate. You can later get the scrollbar back when you
need it. The menu item Toggle Scrollbar in the Window menu inserts/removes
the horizontal scrollbar. The default for subsequent windows is controlled
via the preference 'Hor Scroll Bar' (look under
"Config->Preferences->Window").

Dynamic menus
Alpha uses dynamic menus. This means that some menu items are changed if
you hold down any of the modifier keys. Usually the option key is the one
which reveals the hidden menu items, but there are also a few items which are
revealed by holding down the control or shift keys. Try this out by pulling
down the File menu and holding down one of the option, control, or shift keys.

Tear-off menus
Alpha's menus can be torn off from the menubar to make floating palettes
of them. Clicking on the buttons on the palettes performs the same action
as the corresponding menu item. Note that dynamic menu items are separated
into several buttons, one for each dynamic item.

If the torn off menu has submenus, there will be popup submenus on the
palette. The submenus can in turn be torn off from the palette (as well as
directly from the menu in the menubar).

If a torn off menu belong to a specific mode, the palette will
disappear/reappear whenever you change from/to that mode.

If you do not want to use tear-off menus, you can disable this feature by
unchecking 'Tearoff Menus' in the dialog "Config->Preferences->Appearance".

Bugs:
Buttons in the palettes are not disabled when the corresponding menu
items are.
Torn off submenus belonging to a specific mode are not hidden when you
change from that mode, only the main menu.

Status bar
The stripe across the bottom of the screen is a floating window which is
used to display short messages. This window is called the status bar. Some
functions also uses it to prompt for input of some text.

To the right of the status bar there are three menus.
• Wrap menu. Shows if the lines in the current window are wrapped
automatically and if the wrapping is soft or not. See the Section
Text Wrapping for more information about text wrapping.
• File Attributes menu. Shows various attributes of the current window
that can be changed. What "Mac", "Unix", "IBM", "MPW", "Think", and "None"
means are explained in the Section File formats.
Read only lets you toggle if the current window can be edited or not.
Show invisibles toggles if invisible characters are shown or not. This
affects all windows, not only the current one.
Tab size opens a dialog which lets you set the tab size of the current
window, i.e. how many positions a tab uses.
• Mode menu. Shows the current mode and allows it to be changed.

Finally, to the very right of the status bar the current line and column
are displayed. Clicking opens a dialog that allows a specific line to be
found.

You can't make the status bar go away. However, it can be dragged if you
uncheck 'Lock Status' in the dialog "Config->Preferences->Window".

Funcs menu
Above the vertical scrollbar on the right is an icon with curly braces
('{}'). This is the so called "Funcs" menu. The content of this menu is
mode dependent, but for modes for programming languages it usually lists
function definitions of the the current window. Select a function in the
menu to jump to its definition in the window. Refer the mode specific help
files for details about the Funcs menu for a specific mode. The menu is
built when you press the braces, so it is always up-to-date. By default,
the content in this menu is sorted alphanumerically. This feature can be
turned off via the preference 'Sort Funcs Menu' in the dialog
"Config->Preferences->Appearance", making the menu appear faster on slower
machines.

Power user tip: cmd-opt-K will put up a listpick dialog of the content of
the '{}' menu. As this is usually alphabetical you can type the starting
letters of the index you want to go to.

Marks menu
Below the funcs menu is the "Marks" menu, which pops up over the icon with
the large 'M'. The "Marks" menu lists all marks for the current window, and
allows them to be cleared or automatically created. Marks are a kind
bookmarks in a file and helps you navigate it. The marks are saved when you
save the file. Select an item in this menu to jump to the corresponding
mark in the window. Selecting 'Mark file' will generate marks for the
current window. Which marks are generated is mode dependent. Refer to the
mode specific help files for information about which marks are generated in
a specific mode. For an extended discussion about marks, see the Section
Marks.

Tip: ctrl-cmd-K will put up a listpick dialog with the current marks of
the file.

Icons
Above the Funcs menu is either nothing, a red disk icon, or a lock icon.
The red disk icon indicates that the window is unsaved; clicking on the
icon saves the window. The lock icon indicates that the window is
read-only; command-clicking toggles the lock icon. Note, however, that an
unsaved window cannot be made read-only.

Title bar
Clicking on the window title pulls down a popup menu showing all containing
folders of the window's file. Selecting an item in this menu puts up a open
dialog in the selected folder. Selecting an item in the menu while holding
down the shift key opens the folder in the Finder instead of putting up a
file dialog.

Command-clicking on the title bar anywhere but right on the title pulls
downs the Mark menu. This is also the case you click on the edges of the
window.
Tip: Using the sides of the window lets you access a particular area of the
menu quicker as you can cmd-click in the approximate location of the menu
item you want to select.

Option-clicking on the title bar brings down a menu. The content of this
menu is mode dependent, but not all modes will define the content of the
menu. If that is the case, the menu will contain a list of all files and
folders in the open window's folder. Selecting a file in the menu will open
it. Selecting a folder will open the containing folder in the Finder. Note
that for windows not saved to the disk there will be no menu with files.
Even if the mode will create a menu when option-clicking the title bar, all
files and folders in the window's folder may be added to the menu. This
happens if the number of items in the menu created by the mode is less than
what is specified by the preference 'Min Items In Title Popup' which you
find in the dialog "Config->Preferences->Window".

Split-pane bar
Above the vertical scrollbar, right under the Marks menu ('M') is a black
"split-pane" bar. Double-clicking or dragging the split-pane bar splits the
frontmost window into two separately scrollable panes. You can also use the
menu item 'Split Window' in the Window menu. Either pane can be edited, any
changes appear in both panes if they show the same text. Move from one pane
to the other by clicking in the pane or by typing control-x, then 'o'. Go
back to a single pane by either double-clicking again or dragging the bar
back to the top of the window.

Iconified windows
Alpha can create small icons of the windows, which are ordered along the
right edge of your screen. 'Iconify' (ctrl-I) in the window menu creates an
icon of the frontmost window. If all windows are iconified it expands one
of the windows again.

Checking 'Iconify On Switch' in the dialog "Config->Preferences->Window" will
make Alpha do the following:
• Iconify all open windows when you switch to another app.
• Expand all windows, which were not iconified before switching from Alpha,
when switching back to Alpha.

        File formats

Alpha can read and write files stored in different formats. In the Save
as… dialog you can specify in which format a file should be written through
the popup menus State and Format.
State popup menu
'State' allows you to specify how much extra information should be saved in
files that you use.
MPW     Window position, current selection, tab sizes, and font
        information are saved every time you open and close the file.
Think   Tab sizes, and font information are saved every time you open
        and close the file.
None    No information is saved when you open and close the file.
The state information is saved in the file's resource fork. It is saved
even if you don't modify the file. Saving this information does not change
the modification date of the file.

Note that if a given file already has mpw information in it when the file
is open, Alpha will always update that information when the file is closed.
Note also that marks are always saved in the resource fork whenever a
file is saved, regardless of the 'State'.

Format popup menu
This menu specifies the way Alpha terminates lines. This to make it easier
to share files with other platforms as lines are terminated differently on
different platforms.
Mac     Lines end with a carriage return.
Unix    Lines end with linefeed.
IBM     Lines end with both carriage return and linefeed.
            Typical, isn't it?
Alpha will transparently read and write all three of these formats. If you
are not sharing files with other platforms you don't have to worry about
the format and simply you the default Mac format. Note that if you are
going to be sharing files with a Unix or IBM machine, you probably don't
want anything in the resource fork, so you'd probably want to set
'State' to 'None'.

Both the state and format for a file can be change through the File
attributes popup menu in the status bar.

The default Saved State can be changed in the dialog
"Config->Preferences->Window".

Open file dialog
Alpha's open file dialog looks like the dialog in any other Mac application
except for three extra checkboxes at the bottom.
Read only   Opens the file as read only. That a file is read-only file
            is indicated by a lock icon in the upper right corner of
            the window. Read-only status can be toggled by
            command-clicking on the icon. The default action for
            'space' and 'backspace' when a file is read-only is to page
            forward (closing at the bottom of the file) or backward.
Projector Aware Projector is freeware version control software from Apple
            that is included in MPW. It also runs as a standalone
            application known as SourceServer. It relies on the existence
            of a 'ckid' resource in the files.

            "Projector aware" means that an application

    must)   not remove this ckid resource if one exists (that means if an
            application saves a file by writing a new one, then delete the
            old and rename the new one it must also make sure to copy over
            an existing ckid-resource even if it uses just the data fork)
    should) interpret this 'ckid' resource correctly to treat a file as
            read-only if the ckid resource says that the file is read-only
            and not only if the Finder locked flag is set.

            However, I don't know how Alpha behaves in these two points.

            Finally, a ckid resource can contain a third state between
            writable and read-only. This state is called MRO (modify read
            only). Being a strange term (IMHO) MRO means that a file has
            been modified locally but has not been checked out from the
            version control pool before.

All files   Allows Alpha to open any file rather than just text files.
            (Technically speaking: not only those with file type 'TEXT'.)

Paragraph format
Word processors such as Microsoft Word and MacWrite only put carriage
returns at the end of paragraphs, so that they can wrap the paragraphs on
the fly. This is what is referred to as 'paragraph format'. Alpha does not
transparently convert to and from this format because there are valid
reasons why someone might want to edit a paragraph formatted file while not
in paragraph mode.

Therefore, when Alpha opens a paragraph-mode file, it asks the user whether
or not to remap it. Alpha assumes a file to be in paragraph mode if it
contains any line longer than the value of 'Para Column', which can be set
in the dialog "Config->Preferences->Text". Files can be mapped back to
paragraph mode by using 'Paragraph to Line' in the text menu.

        Modes

Alpha is made for editing text of many different kinds. Therefore Alpha can
switch between many different modes. When Alpha switch between the modes
some of Alpha's functionality changes to better help you to write the
particular kind of text you are editing. For example C++ mode is used to
edit code in the C++ programming language, and HTML mode is used for
editing web pages. Alpha comes with more than 25 modes, most of them being
modes for different programming languages. The default mode is called Text
mode and is used for editing plain text, like this manual for example.
Alpha also switches to Text mode when you open a new untitled window. See
the file Packages for a complete list of them and for links for help for
each of them. This section is only a general discussion about modes.

Simple examples of functionality which changes between the modes are:
• Coloring of the text. Programming language all have special keywords.
Alpha colors these keywords to make the code easier to read, and these words
are naturally different in different programming languages.
• Alpha indents the code to make it easier to read. This is also naturally
done differently for different programming languages.

Most modes also add functionality to Alpha, functionality which is not
available for the basic Text mode. Some modes also have there own menu(s)
which are inserted in the menu bar when switches to the mode in question.
This menu(s) are removed again when Alpha leaves the mode. Some simple
examples of extra functionality in different modes:
• In C++ mode Alpha can help you to quickly type certain language
constructs, such as for loops.
• In HTML mode there is a function to create a link between two web pages.

It is important to know that Alpha has both global menus and functionality,
which are always there regardless of the mode, and mode specific menus and
functionality, which are only there when Alpha is in a specific mode. For
instance, the menus from File to Config and the Window menu (the one with
the three windows icon) are global menus.

When you open a file Alpha always chooses a mode for it. Alpha does its
best to choose the mode you want. Therefore it is important to know how
Alpha chooses the mode. The following is considered:
• The suffix in the file name. For example, 'file.c' is opened in C++ mode
because of the '.c' suffix, 'file.html' is opened in HTML mode because of
the '.html' suffix. You can view and edit the suffix mapping using the menu
item "Config->Preferences->Suffix Mappings…"
In this dialog the suffices for each mode is specified as a list of
patterns matching the file names. In these patterns * stands for 'any
characters', e.g. the pattern '*.c' matches any file name ending by '.c'.
As an example, for Perl mode the default patterns are:
*.pl *.ph *.pm
meaning that any file with a name ending by '.pl', '.ph', or '.pm' will be
opened in Perl mode.
• If the first non-empty line contains a string '-*-Mode: <mode>-*-'
or '-*-<mode>-*-' (without quotes) then Alpha switches to the mode <mode>.
For example, if the first non-empty line contains '-*-HTML-*-' Alpha opens
this file in HTML mode.
• If the first non-empty line reads "#!/dir/subdir/command  ..." then Alpha
tries to find a mode corresponding to 'command'. This kind of line is used
in unix files.
• In some cases Alpha can choose the mode depending on which application
has created the file. One example is that files created by MacPerl are
opened in Perl mode.

You can customize which modes Alpha chooses in the last two cases, see the
Sections modeCreator and unixMode.

You can also manually change mode for a window by selecting one in the mode
popup menu in the status bar. The mode menu is the rightmost of the three
menus in the status bar. You can also change mode using the menu item
"Config->Mode Prefs->Change Mode…"

Once Alpha has chosen a mode for a window, Alpha remembers it when you
switch between the windows, until you manually change the mode for the
window.

Tip: Holding down the shift key while selecting a mode in the mode popup
menu makes Alpha open the help file for the mode instead of changing mode
for the window.
Holding down the option key while selecting a mode in the mode popup
menu makes Alpha give you a description of the mode. However, most of this
description is hardly of any use unless you know Tcl programming.

Global and mode preferences
Alpha has two types or preferences, global and mode preferences.
• Global preferences always apply regardless of the mode. These are set in
the various dialogs "Config->Preferences".
• Mode preferences only apply to windows in that mode, and are set in the
dialog "Config->Mode Prefs->Preferences…". Some modes may also have other
means of setting preferences. Note that in some cases there are mode
preferences which coincide with a global preference. In this case the mode
preference override the global one.

The is also another way of customizing Alpha than setting preferences in
these dialogs. That is using preferences files where you add your own Tcl
code. There is both a global preferences file, opened using
"Config->Preferences->Edit Prefs File" and a mode specific one opened using
"Config->Mode Prefs->Edit Prefs File".

To learn about writing your own code for Alpha, see the section Changing
Alpha's behavior.

        Packages

Alpha has a very flexible mechanism for adding extra functionality. Much of
Alpha's functionality has been bundled into a number of so called packages.
This has two main advantages. First, the user can choose to activate only
those packages he or she wants and totally ignore the other ones. Second,
anybody can write and distribute new packages for Alpha.

The packages come in three flavors:
• Modes. As have been discussed in the previous section, a mode gives Alpha
some functionality useful for editing text for a particular purpose, for
example writing code in various programming languages.
• Menus. A menu is a package which attaches an extra menu to the menu bar.
• Features. A feature gives you some more functionality without attaching a
menu to the menu bar. However, some features adds a new submenu to a menu
or some new menu items to a menu.

In practice the only difference between 'menus' and 'features' is that
'menus' have their own menus in the menu bar.

Alpha comes with a large number of packages. See the file Packages for a
complete list of them and for links for help for each of them. To find help
for a specific package you can also use the menu item
"Config->Packages->Read Help For A Package…"
To learn how to install new packages see the Section Installing New Packages.

Menus and features can be activated and deactivated either globally or for
specific modes. This is done using the menu items
"Config->Preferences->Menus and Features…" and "Config->Mode Prefs->Menus and
Features…"

Activating a menu or feature makes the functionality provided by the menu
or feature available until it is deactivated. Alpha remembers which ones
are active next time you run Alpha. Once a menu or feature is deactivated
it does not affect Alpha's behavior at all. It is then as if it did not
exist. Note, however, that in some cases you the package is not deactivated
until you restart Alpha.

The dialog "Config->Preferences->Menus and Features…" is divided into two
pages, one for menus and one for features.

The page for menus is divided into two sections.
• Usual menus. These are menus designed to be used globally.
• Other possible menus. These are menus designed to be used in a specific
mode or modes.
Thus, normally it is a good idea to only choose between the menus in the
section 'Usual menus'. Although it is possible to activate the other menus
globally, they are usually of no use outside the mode or modes they are
designed for.

The page for features are similarly divided into two sections.
• Usual features. These are features designed to be used globally.
• Other possible features. These are features designed to be used in a
specific mode or modes.
Also in this case it usually only make sense to choose between the ones in
the section 'Usual features'.

        Tiling windows

Alpha provides many different ways to move windows around the screen, most
of which are accessible via the windows menu, i.e the menu with the window
icons. The first four items of the "Windows->Arrange" menu move windows
around a virtual box on the screen, defined by the preferences found in the
dialog "Config->Preferences->Tiling".
Vertically
Tiles 'Num Wins To Tile' number of windows vertically. Preferences which
affects the tiling:
'Tile Top' The position of the upper edge of the top window.
'Def Width' The width of the windows. (Def Width is set in the Windows
preferences dialog.)
'Tile Margin' Controls the gap between the windows.
'Tile Height' Determines the height of the windows by the formula
         (Tile Height + (Tile Margin -1))
height = ________________________________
                Num Wins To Tile
Horizontally
Tiles 'Num Wins To Tile' number of windows horizontally. Preferences which
affects the tiling:
'Tile Height' The height of the windows.
'Tile Left' The position of the left edge of the left window.
'Hor Margin' Controls the gap between the windows.
'Tile Width' Determines the width of the windows by the formula
         (Tile Width + (Hor Margin -1))
width = ________________________________
                Num Wins To Tile
Unequal Vert and Unequal Hor
Tile two window by splitting the space between them, with the proportion
assigned to the first controlled by 'Tile Proportion'.


        Command-double-clicking

Command-double-clicking on a word activates a mode specific function which
uses the word you clicked on as input. In several programming modes, Alpha
tries to find the definition of the word you clicked on. Some examples:

When command-double clicking on a word in a C++ file Alpha first checks if
you clicked on an #include statement. Alpha then tries to open the file.
Next Alpha tries to look up the word in the tag file. If the word is not a
tag, or no tags have been specified, Alpha attempts to lookup the word
through the THINK Reference app. If you would like Apple's Toolbox
Assistant to be used instead, edit the proc 'C++::DblClick'.

In Tcl mode, if you click on a variable Alpha displays its value, if you
click on a command Alpha tries to look it up first in the Tcl folders, then
in "Alpha Commands", and then finally in "Tcl Commands".

        Command-clicking

Command-clicking on any text causes Alpha to try find a URL anywhere near
where you click. If Alpha finds one it sends it to Internet Config which
passes it to the right helper application. Unfortunately, this feature is
rather buggy. Whenever there is a colon nearby where you click Alpha
usually thinks there is a URL, although there is not, and sends it to
Internet Config. If Internet Config returns an error Alpha then interprets
your command-click as a command-double-click instead.

        Undo + Redo

Alpha supports unlimited undo and redo. This means that most changes can be
undone, and then redone, at will. Bear in mind that once you create new
modifications, all changes that you have undone but not redone are lost.
Another point to bear in mind is that saving a buffer to disk flushes the
undo buffer.

        Text Wrapping

Alpha can wrap the text as you type in three different ways. How Alpha
wraps the text can be set for each mode. Presumably you want Alpha to wrap
plain text files, like this one, but not to wrap programming code.
How the wrapping is done is indicated in the leftmost popup menu in the
statusbar, where also the way of wrapping can be changed. A change affects
the current mode, not only the current window. The three ways of wrapping
are:

None    No wrapping.
Wrap    When you type beyond 'Fill Column' positions, Alpha inserts a line
        break to make you continue typing on the next line.
Soft    Soft text wrapping is re-formatting the rest of the paragraph
        on-the-fly as text is inserted and deleted. Soft-wrapping is
        enabled by selecting "Soft" in the wrap popup menu in the status
        bar. The text to be wrapped is delimited by the current line and
        the last line in the current paragraph. Wrapping occurs after
        insertions that result in the current line becoming longer than
        'Wrap High' characters long (tabs counted as one character), or
        deletions where the length of the line (tabs likewise) becomes less
        than 'Wrap Low' characters long.
        The soft wrapping is not "true" soft wrapping like the one used by
        word processors. Alpha rather reformat the paragraph and insert line
        breaks at new positions on-the-fly.

The values for 'Fill Column', 'Wrap High', and 'Wrap Low' can be changed
in the dialog "Config->Preferences->Text".

        Indentation

Alpha automatically indents the text for you to make it easier to read. How
the text is indented is mode dependent. In programming modes Alpha will
indent blocks of code, like e.g. an if-else statement in
C/C++/Java/JavaScript etc.

if (a == 5) {
    b = 5;
} else {
    b = 17;
}

How many positions the code is indented is determined by the preference
'Indentation Amount', which can be set in the dialog
"Config->Preferences->Electrics". By default the code is indented 4
positions for each level of indentation.

Whether the code will be indented by spaces or tabs is dependent of the tab
size, which can be set in the dialog "Config->Preferences->Appearance". By
default the tab size is 8. Thus with the default setting clearly your code
can't be indented using tabs alone. 'Odd' indents will require a number of
tabs plus 4 spaces, and 'Even' indents will be ok with just tabs.

If you want the code to be indented with spaces only, activate the feature
"Indent Using Spaces Only" in the dialog "Config->Preferences->Menus and
Features…".

        Electrics - automatic typing by Alpha

The term "electric" is used in the sense of "automatic, power assisted
behavior", which is intended to save time, keystrokes, and brainpower. All
the "electric" features are features, which makes Alpha do automatic typing
for you. The exact behavior is mode dependent. The various electric
features and enabled/disabled either globally in the dialog
'Config->Preferences->Menus And Features…' or per mode in the dialog
'Config->Mode Prefs->Menus And Features…'.

Electric return
Enabling the 'Electric Return' feature tells Alpha to indent the following
line automatically whenever you press return.

Electric braces
Enabling the 'Electric Braces' feature tells Alpha to treat the left or
right brace '{', '}' keys as special keypresses which enter the '{' or '}'
character, followed by a return and then indent the following line
correctly. It is useful for those programming modes in which '{' and '}'
are used to delineate blocks of code in 'for' loops or 'if-then-else'
groups etc.
If you only want a '{' or '}' without the electric behavior, type option-{
or option-}.

Electric semicolon
Enabling the 'Electric Semicolon' feature tells Alpha to treat the
semicolon keys ';' as special keypresses which enters the ';' character
followed by a return and then indents the following line correctly. It is
useful for some programming modes in which ';' normally ends a line. The
';' key is context-dependent so you can still enter a for( ; ; ) loop in C
mode (for instance) without Alpha messing things up.
If you want a ';' without the electric behavior, type option-;.

Electric colon
Enabling the 'Electric Colon' feature tells Alpha to indent lines ending by
a colon differently. This is for those programming modes which uses
switch-case statements like e.g. C/C++, Java, and JavaScript.

Electric completions
Enabling the 'Elec Completions' feature gives you a set of features to save
you key strokes. When you invoke it Alpha tries to expand what you have just
typed to give the rest of what you want. Electric completion is invoked by
typing command-tab or F1. The documentation will always refer to
command-tab as being the key combination for electric completion. However,
command-tab conflicts with the application switching feature introduced in
Mac OS 8.5. Read more about this conflict below.

Alpha can complete what you just have typed in several different ways, and
the behavior vary from mode to mode. In many modes Alpha tries a set of
different ways to complete and continues until one of them succeed (or all
fails). Let us start with the simplest kind of completion, but which
normally is tried last when everything else has failed.

Word completion: Type the first few letters of a word and hit command-tab
(or F1). Alpha will then search the document for a word which begins with
these letters. If one is found Alpha completes the word you have just typed
the first letters of. If this is not the word you want, hit command-tab
again and Alpha continues searching for another one beginning with the same
letters. Hitting command-tab repeatedly will cycle through all words in the
document beginning with these letters until no more such word is found.
Alpha always starts searching backwards from the point where you are until
is reaches the top of the document, then is continues searching forwards
from the point where you are until the end of the document.

An example: Typing 'com' right here and hitting command-tab will expand
this to 'command', which is the first word beginning by 'com' found above.
Hitting command-tab again without moving the insertion point will expand it
it 'completes', which is the next word beginning by 'com' found above.

Command template completion: For for loops, if statements and similar
constructs used in programming languages Alpha can insert a template. As
an example let's make an 'if' template for C, C++, Java, and other
languages using the same construct. Simply type

if

(when Alpha is in C, C++, or Java etc. mode!) and hit command-tab. Alpha
then inserts a template

if (|){
    •
} •

with the insertion point between the parentheses. The bullets '•', which
are inserted are called template stops. When you hit tab, Alpha jumps to
the next template stop and deletes. To use the template first type the
condition and then hit tab. Alpha the jumps to the first bullet and deletes
it. Then type the body of the if statement and finally hit tab again to
jump to the last template stop. Note! The feature 'Electric tab' must be
enabled for the mode in question to be able to jump between the template
stops with tab, see below.

This section has only been a short introduction to electric completions.
More detailed help is found in ElecCompletions Help.

Some modes also have their own tutorial how to use completions in the mode.
The tutorial is opened using 'Config->Mode Prefs->Completions Tutorial'.
See also the documentation for the mode.

Electric tab
Enabling the 'Electric Tab' feature allows Alpha you to use the functions
'Indent or Next Stop' and 'Complete or Tab' as any of your 'Special Keys'
bindings. By default 'tab' is invokes the function 'Indent or Next Stop',
but there is no key which invokes 'Tab or Complete'.
Indent or Next Stop will first look forward for a template stop '•'. If one
is found Alpha jumps to it and deletes it. If no • is found Alpha will
instead indent the current line.
Complete or Tab will make an electric completion.
If you want to insert a normal 'tab', type option-tab.

Electric expansions
Enabling the 'Elec Expansions' feature provides you with a special kind of
word completion. When you find yourself typing a lot of variable and
function names over and over, and these names are word-combinations where
the name is formed by either capitalizing each word or separating them with
an underscore, just type the initial letter of each word and invoke
electric expansion instead. This is often shorter and more natural than
typing a few letter and using electric completions to make a word
completion. Electric expansion is invoked by typing command-space.

The string you are going to use expansion on is entered in lowercase. The
words in the target you are trying to hit have to start with a capital
(except the first word), or, be separated by an underscore.

The hint can be embedded between non-alphabetic characters and certain
punctuation marks ( '[', '(', '{', ',', ';', ':', ''', '"', ']', ')', '}'
). The expanded hint remains so embedded, and the cursor appears one space
beyond the trailing punctuation.

An example: Let's say there is a word 'someLongWord' in the file. Then
typing 'slw' and hitting command-space will expand 'slw' to 'someLongWord'.

Another example: Let's say there is a word 'some_long_word' in the file. Then
typing 'slw' and hitting command-space will expand 'slw' to 'some_long_word'.

This section has only been a short introduction to electric expansions.
More detailed help is found in ElecCompletions Help. Some modes may also
their own special expansions features, see the help files for the respective
modes.

Special keys dialog

The dialog "Config->Special Keys…" is used to define the keys which
activate the electric completion and expansion functions and which let
you jump between the template stops. You can define keys for the following
functions:

Function                Action
Expand                  Electric expansion.
Next stop or indent     Alpha first looks forward for a template stop '•'.
                        If one is found Alpha jumps to it and deletes it.
                        If no • is found Alpha will instead indent the
                        current line. This requires that 'electric tab' is
                        enabled, otherwise a tab is inserted.
nth Stop                Jumps to the nth template stop.
Complete or Tab         If 'electric tab' is enabled Alpha will make an
                        electric completion, otherwise a tab is inserted.
Next stop               Jump to the next template stop '•' and delete it.
Clear all stops         Delete all template stops '•' in the window.
Complete                Electric completion.
Real tab                Inserts a tab.
Prev stop               Jump to the closest template stop '•' before the
                        current position and delete it.

There are two predefined sets of key bindings for these functions. The
alternative set is define to use key bindings like those which are used in
Emacs. In the dialog 'Config->Special Keys…' you can choose one of these
two sets of bindings or define your own.

Function                Default binding             Alternative binding
Expand                  command-space               command-space
Next stop or indent     tab                         no binding
nth Stop                control-tab                 control-tab
Complete or Tab         no binding                  tab
Next stop               no binding                  control-j
Clear all stops         shift-control-tab           shift-control-tab
Complete                command-tab                 no binding
Real tab                option-tab                  option-tab
Prev stop               shift-tab                   shift-control-j

Electric completions and Mac OS 8.5
In Mac OS 8.5 command-tab is used to switch between application. This
conflicts with Alpha's use of command-tab for electric completions. This
problem can be solved in three different ways:
• By default 'Electric completion' in Alpha is also bound to F1. Use F1
instead of command-tab. However, the package "Electric menu" uses F1
for someting else, so if you activate the "Electric menu", using F1 for
electric completions is not possible.
• Use the dialog "Config->Special Keys…" to define a new key combination for
Electric completion.
• Change the key combination for switching applications in Mac OS. This is
done in the following way:
    • Open the Help Viewer
    • Search on "tab" (or whatever is appropriate in your language)
    • Select "Switching between open programs"
    • Scroll down to the end of "Switching from one program to another"
    • Click "Help me modify the keyboard shortcuts"

        Coloring

Alpha supports automatic coloring of the text. The way Alpha colors the
text depends on the current mode. There are basically three different
things Alpha can color.
Keywords    A set of words with a special meaning, e.g. keywords in
            programming languages.
Strings     Text delimited by double quotes. Alpha can color single-line
            strings only.
Comments    Comments in programming code.
For details about the coloring in a specific mode, see the help file for
the mode. The coloring support in the different modes differ and some
modes have a more complex coloring support than just the basic things
mentioned above.

Colors for keywords, strings, and comments (for applicable modes) can all
be changed via the "Config->Mode Prefs->Preferences…" menu item. Some
modes may offer more extensive customization.

By default there are seven different colors to choose between, blue, cyan,
green, magenta, red, white, and yellow. If you wish you can redefine these
via the menu "Config->Redefine Colors". For instance, you can redefine 'red',
and any text that is currently red will then be the new color you specify.
In addition, there are eight other colors 'Color_9' through 'Color_15'
which you can use to define your own colors. Note that by default these
colors do not show up in the mode preferences dialog because until you have
given them a value they are undefined.

Coloring can be turned off completely by unchecking 'Coloring' in the
dialog "Config->Preferences->Appearance".

Additionally, Alpha allows the text color and window background to be
changed. These are changed by redefining 'Foreground' and 'Background' in
the "Config->Redefine Colors" menu.

Advanced coloring customization

If you don't find the customization in the mode preferences dialog
sufficient, you can customize the coloring by adding some Tcl code to the
mode preferences file. This file is opened via the "Config->Mode
Prefs->Edit Prefs File" menu item. Coloring is defined using the command
regModeKeywords. For a complete descriptions how to use regModeKeywords,
see the file Alpha Commands. Here follows a few examples.

As an example the line:

    regModeKeywords -a -k blue Fort {blah bladdity}

will add the keywords 'blah' and 'bladdity' colored blue in Fortran mode.

        Search and Replace

Alpha has a full repertoire of searching commands. The 'Find' menu item in
the Search menu brings up a dialog allowing the search and replacement text
to be specified. Alpha can search either the current open window or a set
of files.
The dialog also allows the following options:
Forward         To search the text forwards or backwards. This does not apply when
                multiple files are searched.
Ignore Case     Whether the search should match case or not.
Word Match      Whether the search should match only complete words or not.
Batch           When making a batch search, a list of all matches in the
                fileset or current window are displayed in a new
                browser window. A particular match can be displayed by
                moving the cursor to a line in the file of matches and
                hitting "return".
Grep            The search and replace text strings are interpreted as
                regular expression. The word 'grep' comes from the unix
                command with the same name.
Mult Files      To search through all files in a given file set. Checking
                the 'Mult Files' box brings up a new popup menu. In this
                menu you can choose which fileset to search. You can either
                select an existing fileset in the menu or create a new one
                by selecting "New Fileset…". Read more about fileset in the
                file Filesets Help.
                In addition to the current filesets, the menu has an item
                called 'Directory Scan'. This allows you to specify a
                folder that will be searched. This folder is also saved at
                the end of the menu for future searches.

And finally, Alpha allows a library of useful search and replace texts to
be defined. This library is used and edited in the popup menu 'Patterns'.
Selecting a pattern from the menu inserts the search and replace strings in
the dialog. In addition
Remember Pattern creates a new item in the menu from the current search and
replace strings.
Delete Pattern lets you delete a pattern from the menu.

Incremental Searches
Emacs users will be happy that both forward and backward incremental
searches are implemented. Incremental searches bypass the normal search
dialog and search for the current text after each keystroke. The result is
often much faster and less intrusive. The menu items 'Quick Find' and
'Reverse Quick Find' in the Search menu are the forward and backward
incremental searches respectively. Start the search either from the menu or
by typing ctrl-s or ctrl-r, then type the word you are searching for. After
each letter you've typed Alpha jumps to the nearest point in the text
matching what you have typed so far. The search string is also displayed in
the status bar.

Typing ctrl-s or ctrl-r again while an incremental search is in progress
causes the search to proceed to the next instance of the current text.
Incremental search mode is exited when any other command (executed through
the menus or through bindings that include at least one of the control key
and the option key) is executed, or when the escape or delete key is used.
Typing control-w while incremental search is active causes all the
characters to the end of the next word boundary to be added to the search.

        Browser Window

Browser windows are used to list the result of batch searches, as well as
other similar lists. Each line in the browser window refer to a certain
line in a file, in the case of batch searches the lines where what you
searched for have been found. Navigate the windows using the up and down
arrows, and jump to the match - i.e. the line in the file referred to by
the line in the browser window - by hitting 'return'.

The browser windows are actually in a special mode, the browser mode. The
complete set of keybindings in this mode is:

uparrow             move up one line in the window and select the line
ctrl-p                                      -"-
delete                                      -"-
downarrow           move down one line in the window and select the line
ctrl-n                                      -"-
space                                       -"-
return              go to match
enter                   -"-
ctrl-C ctrl-C           -"-

In the Search menu there is also a very useful command 'Next Match'.
Regardless which window is frontmost, it brings the browser window to the
front, navigate down one line, and goes to the match of that line. Thus,
this gives you a quick way to jump to all matches without having to
manually bring the browser window to the front.

        Regular Expressions

Regular expressions are used to find the part of a string which matches a
certain pattern.

A regular expression is zero or more branches, separated by `|'. It matches
anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the
first, followed by a match for the second, etc.

A piece is an atom possibly followed by `*', `+', or `?'. An atom followed
by `*' matches a sequence of 0 or more matches of the atom. An atom
followed by `+' matches a sequence of 1 or more matches of the atom. An
atom followed by `?' matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the
regular expression), a range (see below), `.' (matching any single
character), `^' (matching the null string at the beginning of the input
string), `$' (matching the null string at the end of the input string), a
`\' followed by a single character (matching that character), or a single
character with no other significance (matching that character).

A range is a sequence of characters enclosed in `[]'. It normally matches
any single character from the sequence. If the sequence begins with `^', it
matches any single character not from the rest of the sequence. If two
characters in the sequence are separated by `-', this is shorthand for the
full list of ASCII characters between them (e.g. `[0-9]' matches any
decimal digit). To include a literal `]' in the sequence, make it the first
character (following a possible `^'). To include a literal `-', make it the
first or last character.

If a regular expression could match two different parts of the input
string, it will match the one which begins earliest. If both begin in the
same place but match different lengths, or match the same length in
different ways, life gets messier, as follows.

In general, the possibilities in a list of branches are considered in
left-to-right order, the possibilities for `*', `+', and `?' are considered
longest-first, nested constructs are considered from the outermost in, and
concatenated constructs are considered leftmost-first. The match that will
be chosen is the one that uses the earliest possibility in the first choice
that has to be made. If there is more than one choice, the next will be
made in the same manner (earliest possibility) subject to the decision on
the first choice. And so forth.

For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
successful overall match, it is chosen. Since the `b' is already spoken
for, the `b*' must match its last possibility-the empty string-since it
must respect the earlier choice.

In the particular case where no `|'s are present and there is only one `*',
`+', or `?', the net effect is that the longest possible match will be
chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x',
due to the begins-earliest rule. (In effect, the decision on where to start
the match is the first choice to be made, hence subsequent choices must
respect it even if this leads them to less-preferred alternatives.)

To summarize, regular expressions are built up of the following pieces:

 c        literal char.
 ^        beginning of line.
 $        end of line.
 .        any character except carriage return.
 [...]    character class, can use ranges such as '0-9'.
          inside classes. Matches one character of the
          enclosed choices. Ex: '[ac0-2]' matches 'a',
          'c', '0', '1', or '2'.
 [^...]   negated character class, matches anything but
          the enclosed characters. ']' can be included
          by putting it immediately after the '^'.
 \t       tab.
 \r       carriage return or line break.
 *        zero or more occurrences of the previous
          pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
          'abbb' etc.
 +        one or more occurrences of the previous
          pattern.
 ?        zero or one occurrences of the previous
          pattern. Ex: 'ab?' matches 'a' or 'ab'.
 a|b      matches either a or b. If enclosed in
          parenthesis, the extent of the alternated
          expressions is limited. Ex: (pete|bob)
          matches either 'pete' or 'bob'.
 (...)    The interior elements are grouped together.

Regular expressions constructed from the above elements can be
concatenated to create larger expressions.

The parenthesis also define substrings of the total matched string that
can be used either later during substitution. The substring delimited by
the pair of parenthesis that includes the nth left paren is denoted \n,
where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.

[examples to be added]

        File Patterns

Some functions require that you give a file pattern which specifies a set
of file names, e.g. if you want to change the suffix mappings you must give
a pattern specifying which files should be opened in a certain mode, and as
another example if you want to create a fileset you must give a pattern
specifying which files should belong in the fileset.

A file pattern is given as a string including special characters, which
allow automatic substitution of characters in file names.

    ?           Matches any single character.

    *           Matches any sequence of zero or more characters.

    [chars]     Matches any single character in chars. If chars contains a
                sequence of the form a-b then any character between a and b
                (inclusive) will match. To match '-' give it as the first
                character between the brackets.

    \x          Matches the character x. This is useful if you want to
                match any of the special characters, e.g to matching '*' is
                done by the pattern '\*'.

    {a,b,...}   Matches any of the strings a, b, etc.

Some examples of how to use file patterns:
• To match any file ending by '.c' use the pattern '*.c'. This will match
files with names like 'blah.c' 'bladdity.c' 'gghjcdhj.c'.
• To match any file ending by '.c' or '.h' use the pattern '*.{c,h}'. This
will match files with names like 'blah.c' 'blah.h' 'bladdity.c'
'bladdity.h'.
• Lets say you have files with names 'chapter1.tex', 'chapter2.tex' through
'chapter50.tex'. To match the first 9 chapters you could use the pattern
'chapter?.tex' This will match the files 'chapter1.tex' through
'chapter9.tex'. Another pattern which would match the same files is
'chapter[1-9].tex'.
• To match the files 'chapter1.tex' through 'chapter9.tex' and
simultaneously files 'chapter1.log' through 'chapter9.log' you can use the
pattern 'chapter[1-9].{tex,log}'

        Marks

Alpha allows the user to use "marks" to remember positions in files. Marks
"float". That is, if a mark is initially at position 312 and then five
characters are inserted at location 297, the mark's new value will be 317.
Alpha uses three different types of marks.

The first is generically referred to as "the mark". The mark is set to the
current insertion point by the command 'Set Mark' (control-space). (This
requires that the Emacs feature is active.) The position in the file
indicated by the blinking cursor is referred to as the current insertion
point. Many commands (such as "cut" and "copy") can operate either on the
currently selected (hilighted) text, or the text between the current
insertion point and "the mark". For example, if you move the cursor to the
beginning of the word "allybaba", hit control-space (the status bar should
say "Mark set"), move to the end of the word and hit option-W (the status
bar should say "Region copied"), the effect is the same as if you had used
the mouse to select the text and then selected the "Copy" command from the
"Edit" menu.

The second type of mark are the permanent marks. Permanent marks are set,
removed, and moved-to through the three corresponding menu items in the
"Search->Named Marks" menu. Permanent marks differ from the generic mark in
that they have names, there can be any number of them, and they are saved
in the resource fork if the file is subsequently saved.

Permanent marks can be accessed via the "Search->Named Marks" menu items,
by a popup menu called by mousing down on the M icon above a vertical
scrollbar, or by command-mousing on a window's titlebar.

        International Users

There is a basic problem international users will notice, which have to do
with the fact that the keyboard layouts are different in different countries.
Therefore some keybindings in Alpha may not work with all keyboards. For
example, on a Swiss keyboard, '/' is shift-7 (which means you have to press
shift to get '/'. This means there is no difference between cmd-/ and
shift-cmd-/ on such a keyboard. In Alpha these are bound separately to
'zoom' and 'singlePage'.

If you're using a western keyboard Alpha can solve some of these problem
for you.

First: Activate the "International Menus" feature. It replaces some
keybindings in the menus and solves problems like the one just described.
However, only key bindings in the global menus "File" to "Windows" are
modified. Any other menu may still have problems.

Second: Tell Alpha which keyboard layout you're using in the preferences
dialog "Config->Preferences->International". (In a future version, Alpha
should be able to get this information from the OS directly.) This will
make sure that some bindings not defined in the menus work, e.g. that the
electric braces work. However, problematic bindings defined in the various
packages are usually not cured by this.

Which menu items are affected?

The menu items that the International Menus package change are (depending
on which keyboard layout you use, some of these may remain unchanged):

Edit menu: Twiddle, Twiddle Words, Shift Left/Right, Shift Left/Right Space
Search menu: Return to Bookmark, Goto Line, Mark Hilite
Windows menu: Zoom, Default Size, Choose A Window

Teaching Alpha new keyboard layouts
If you're not using a western keyboard or if you do encounter any problems,
reading the following section will help to clarify things and should help
you to fix the problem. This section requires that you first read the
section Changing Alpha's behavior. If you need help defining
a new keyboard layout, subscribe to the ALPHA-D mailing list and ask for help.

To solve the problem with bindings in the menus you can use the
menu::replaceWith command. To solve the problem with the Swiss keyboard
described above you would add the following to your preferences file:

    menu::replaceWith winMenu [list "//<Szoom" "//<S<I<OsinglePage"] \
        items "<S//zoom" "<S<O<U/=singlePage"

To define your keyboard layout, add a line like this to your preferences
file:

    set "keyboards(U.S.)" {
     {§1234567890-=[];'\`,./}
     {±!@#$%^&*()_+{}:"|~<>?}
     <U/[
     <U/]
    }

The first two lines tell Alpha how to map using the 'shift' key. Shift maps
each item in the upper string into the corresponding item in the lower
string.

The third and forth lines defines the keybindings for the left and right
braces, in this example to shift-[ and shift-].

See the file alphaDefinitions.tcl for examples of keyboard layout
definitions.

If you define an array entry keyboards(my-country), then you can just
select that in the international prefs dialog, and Alpha will set the flags
correctly. You can then send that keyboard array entry to the ALPHA-D
mailing list for inclusion in a future version of Alpha.

If a package wishes to be told when the keyboard changes, it can do
that by registering with the 'removekeyboard' or 'keyboard' hooks like
this:

    # tell me when we switch to a "Swiss German" keyboard
    hook::register keyboard keys::swiss "Swiss German"
    # tell me when we disable a keyboard
    hook::register removekeyboard my_disable_proc
    # tell me when we enable a keyboard
    hook::register keyboard my_enable_proc

In this way a clever package could remove the need for restarting
Alpha by unbinding and then rebinding all necessary items.

        File Comparison

With Alpha you can compare files and display the differences in them. Among
other things, this allows you to easily pinpoint what has changed between
two different versions of the same file. Using the menu "Utils->Compare" you
can either compare the two topmost windows, or two arbitrary files or two
entire folders. In the case of two folders each pair of files with
identical names in the two folders are compared. It is also indicated which
files are only found in one of the folders.

The comparison is done using a port of the unix GNU diff program.

Alpha opens the two files in windows at the top of the screen with the diff
file at the bottom. You can navigate between individual differences in the
diff file by using the Up and Down arrows. The section of the files which
differ are then selected in the two files.

This section has only been a short introduction to the use of file
comparison with Alpha. Read more in the file Diff Help

Bugs: File comparison only works if the files have Mac line terminations.

        Helper Applications

Alpha uses many helper application, e.g. a web browser and an ftp client.
You can choose which helpers to use by the menu item
"Config->Preferences->Helper Applications". Select which helper app you want
to change.

Now, in some cases a dialog is opened with a popup menu with some popular
apps of the appropriate type. Either choose one from the popup menu, or
select 'Locate manually' and click OK to locate the app on your disk.

In some cases a file dialog is directly opened to let you locate the
helper app.

        Backups

Alpha can automatically make a backup copy for you of the old version of a
file whenever you save changes. This is done if you check 'Backup' in the
preferences dialog "Config->Preferences->Backups". By default the backup file
is saved in the same folder, and its name is formed by suffixing a tilde to
the name of the saved file. The backup behavior can be modified by changing
the following preferences in the dialog "Config->Preferences->Backups":

Backup              Check this if you want Alpha to make backups.
Backup Folder       The folder where to save the backups. If none specified
                    the backups are saved in the same folder as the
                    original.
Backup Extension    The extension to add to name of the backup file. Don't
                    pick a long extension! The total file name mustn't be
                    more than 31 characters.
Backup Age Requirement In Hours     A new backup file is only created if the
                    old backup file is older than this.

If you have chosen a backup folder and want to go back to the default
behavior of saving the backup in the document's folder this is how to do
it:
Delete or rename the backup folder. Alpha will then ask you if you want to
create the backup folder. If you answer 'No' Alpha will revert to the
default behavior.

Auto saving
Alpha can automatically save the documents for you after a certain number
of changes. This is done if you check 'Auto Save' in the preferences dialog
"Config->Preferences->Backups". Alpha then saves the documents every 'Changes
Lim' changes. 'Changes Lim' can be set in the same preferences dialog. Note
that Untitled windows are not autosaved.

        Spell Checking

Alpha has the capability to interact with the spell-checker 'Excalibur',
written by Robert Gottshall and Rick Zaccone. The menu item 'Spellcheck
Window' is always available in the "Text" menu. Selecting this item will
start up Excalibur and open the current window in Excalibur.
For version 1.4 and earlier, if Alpha has to launch Excalibur you will need
to dismiss Excalibur's opening dialog by hitting the Cancel button.
Subsequent selections of the menu item will switch right into Excalibur
with the correct file displayed.
When switching back from Excalibur to Alpha, Alpha reads the corrected
version of the file into the current window.

There is also a menu item 'Spellcheck Selection'. This copies the current
selection to the clipboard and switches to Excalibur. You can then use
'Open Clipboard' in Excalibur's File menu to spellcheck the selection.
When you switch back to Alpha you have to paste the corrected text
yourself.

Excalibur can be obtained from http://www.eg.bucknell.edu/~excalibr/excalibur.html

        Tags

Alpha supports the use of tags to find declarations of functions; by
default this is set up only for 'C'. When searching for a tag, Alpha looks
for the tag file specified by the 'Tag File' preference, which can be set
in the dialog "Config->Preferences->Tags". Alpha's tag generating routines
use the regular expression in the preference 'Func Expr' to look for
function declarations. In other words, we don't parse the text. If you
declare your functions differently, you can change 'Func Expr' to suit your
own style. Alpha currently uses the following regular expression to find C
function declarations:

              ^[^ \t\(#\r/@].*\(.*\)$

Although complicated, this expression makes sense if you slowly wade
through it. The string that we are looking for must take up an entire
line. It must begin with a character other than '\t', '#', '\r', '/', ' ',
'(', or '@'. There must be a set of parenthesis.

Note that not only can you customize this to your style of 'C'
declarations, you could also use it to generate tags for other languages.
The only thing you need to bear in mind is that the tag routines use the
complete word previous to the first '(' in the selected line as the
function's name. If there is no '(' in the selected line, the last word in
the line is used. Therefore, Pascal procedures with or without parameters
can be identified.

Caveat: Apple's list manager can't handle more than 32k of text in the
entire list, so there is a practical limit of 2000 or so tags in your
project.

        Calculator

Alpha has its own calculator. This is just a quick-and-dirty RPN stack
calculator, which works on both signed and unsigned decimals, hex integers,
and floating point.

Operations:
    +,-,*,/,|,&,%   Top of stack is 'y', next is 'x'. Does x OP y.
    ~               bitwise NOT
    ^               x eor y
    <               x << y
    >               x >> y
    c               change y's sign
    q               duplicate y
    i               swap x and y
    m               switch signed/unsigned/hex modes
    x               show current mode
    h or ?          help
    <delete>        pop stack
    <space>         enter number
    opt-P           pi (3.14159265358979323)
    shift-opt-E     e  (2.718281828459045)

Invoke from the Utils menu, holding down the shift key.

        Alpha's Menus

This section is an explanation of Alpha's main menus, from "File" to
"Windows" (menu with the window icons). The menu items listed here are the
ones available when no features are enabled in the dialog
"Config->Preferences->Menus and Features…". Some of these features add new
menu items or new submenus to Alpha's main menus.

Alpha uses Ramon Felciano's Mercury MDEF to display menus. In addition to
allowing other modifiers to be shown in the menu, this MDEF also allows
alternates, items that change depending on the state of the modifier keys.
Alternate items are tagged below by the modifier that must be pressed to
display it.

File
    New                     New file.
    Open…                   Open file.
    Close                   Close file.
    Close All (option)      Close all files.
    Close Float (shift)     Close a palette.

    Save                    Save file.
    Save All (option)       Save all files.
    Save Unmodified (control) Save file without changing the modification
                            date.
    SaveAs…                 Prompt for name to same file under.
    Save A Copy As… (option) Save a copy of the open window.
    Rename To… (shift)      Rename file.

    Revert                  Revert to last saved version, throw away undo history.
    Revert To Backup (option) Revert to last backup copy, if any.

    File Utils
        File Remove…        Remove a file.
        File Info…          Display/edit info about a file.
        Text to Alpha       Set creator a text files to Alpha.
        Show in Finder      Select the front window in the Finder.

    Page Setup…             Set print options.
    Print…                  Print window.
    Print All (option)      Print all windows.

    Quit                    Quit Alpha.

Edit
    Undo                    Undo.
    Redo                    Redo.

    Cut                     Cut selection to scrap.
    Copy                    Copy selection to scrap.
    Paste                   Paste from scrap.
    Select All              Select entire file.
    Select Paragraph (option)   Select current paragraph.
    Clear                   Delete selection.

    Twiddle                 Exchange characters bracketing the selection point.
    Twiddle Words (option)  Exchange words bracketing the selection point.

    Shift Left              Shift selection left one tab.
    Shift Left Space (option)   Shift selection left one space.
    Shift Right             Shift selection right one tab.
    Shift Right Space (option)  Shift selection right one space.
    Balance                 Select text out to the next set of matching braces.

Text
    Fill Paragraph          "Fill" paragraph that contains the insertion point.
    Wrap Paragraph (option) Break lines longer than 'fillColumn' in paragraph
                            containing the insertion point.
    Sentence Paragraph (option-shift) - Forces each sentence to start on new
                            line.
    Fill Region             "Fill" selection subject to 'leftFillColumn' and
                            'fillColumn'.
    Wrap Region (option)    Break lines longer than 'fillColumn' in selection.
    Sentence Region (option-shift) - Forces each sentence to start on new
                            line.

    Line To Paragraph       Convert a line to a paragraph.
    Paragraph to Line (option) Convert a paragraph to single line.

    Sort Lines              Sort selected lines.
    Reverse Sort (option)   Sort selected lines backwards.
    Spellcheck Window       See here.
    Spellcheck Selection (control)

    Zap Invisibles          Delete all chars in file with ASCII code < 32, except
                            for LF, TAB and CR.
    Tabs To Spaces          Convert tabs to space runs.
    Spaces To Tabs (option) Convert space runs to tabs.

    Indent Line             Indent the current line.
    Indent Selection (option) Indent the selection.

    Upcase Region           Upcase all chars in region.
    Downcase Region (option) Downcase all chars in region.

    Strings
        Insert Prefix           Prepend string 'prefixString' to every line in
                                selection.
        Remove Prefix (option)  Remove prefix string from lines in selection.
        Insert Suffix           Append string 'suffixString' to every line in
                                selection.
        Remove Suffix (option)  Remove suffix string from lines in selection.
        Set Prefix              Change prefix string.
        Set Suffix              Change suffix string.
    Comment Line            Comment out line, considering mode.
    Uncomment Line (option) Un-comment line, considering mode.
    Comment Box             Create a comment box around selected text.
    Uncomment Box (option)  Remove such a comment box.
    Comment Paragraph       Comment out a paragraph.
    Uncomment Paragraph     Uncomment a paragraph.

Search
    Find…                   Present a search dialog.
    Search Start (option)   Return selection point to where the last search
                            started.
    Find Again              Search forward again with same settings.
    Find Again Backward (option)    Search backward again with same settings.
    Find in Next File       Restart multiple-file search in next file after
                            stopping at a match.
    Enter Search String     Use the current selection as the search text.
    Enter Replace String (option)   Use the current selection as replace text.

    Quick Find              Incremental search forward (grep, match words off,
                            ignore case on). Type chars to define string,
                            control-w adds the current word to the search
                            string, control-s/r search for the same string again.
    Quick Find Regexp (option)  Same as Quick Find but lets you use a regular
                            expression.
    Reverse Quick Find      Same thing in reverse.

    Replace                 Replace the selection.
    Replace and Find Again  Replace the selection and search again forward.
    Replace All             Replace all of occurances of the search string
                            in the rest of the file.
    Replace in Fileset (control)    Global replace in fileset.

    Place Bookmark          Set a book mark at the current position, pushing it
                            onto a "stack".
    Return to Bookmark      Pop last bookmark from stack and go to it.
    Goto Line               Goto specific line number.

    Matching Lines          Find all lines that match a regular expression and
                            summarize in new window.
    Goto Match              Jump to the original text specified by the current
                            line in a "Batch Find" or "Matching Lines" window.
    Next Match              Jump to the original text specified by the next
                            line in a "Batch Find" or "Matching Lines" window.
    Goto Func               The same as selection an item in the Funcs menu (the
                            one with two curly braces at the right top of the window)
    Goto File Mark          The same as selection an item in the Marks menu (the
                            one with the M icon at the right top of the window)
    Mark Hilite             Select text last manipulated, such as from a paste.
    Named Marks->           Manipulating named marks.
    Unnamed Marks
        Set…
        Exchange Point And Mark

Utils
    Compare
        Windows             Compare top two windows, sending output to a third.
                            Selecting a line in the third window and hitting
                            return (or enter) moves that line to the top of
                            the window.
        Files               Same as above, but prompts for files.
        Directories         As above, but works for entire folders.

    Win Utils
        Insert Path Name…   Prompt for a file and insert complete pathname in
                            window.
        Insert File…        Insert the text of another file.

    Ascii Etc
        Quote Char          Wait for key press and insert key.
        Key Code            Wait for key press and insert keycode and modifier
                            string suitable for key binding.
        Key Ascii           Same as above, but use ascii form.
        Get Ascii           Display ascii code for char to right of insertion.
        Insert Ascii        Prompt for ascii code and insert character.

    Shell                   Start up command-line shell that interprets Tcl
                            commands. The shell has a few csh-type features,
                            such as 'ls', 'rm', etc. commands, as well as file
                            completion with the TAB key.
    Toolserver Shell (control) See here.
    Calculator (shift)      See here.

    Word Count              Count lines, words, chars in window.
    Send URL                Send selection as URL to proper internet application.
    Cmd-Double Click        See here.

Config
    Preferences             Set global preferences.
        Menus and Features… Change global menus and features.
        Suffix Mappings…    Displays and allows editing of suffixes (really
                            filename patterns) for all existing modes.
        Edit Prefs File     Put your own arbitrary startup code here.
                            Loaded after all standard Tcl code.
        Interface Preferences etc. The rest of this menu is used to set
                            preferences.

    Packages
        Miscellaneous Packages…     Set preferences for packages.
        Describe A Package…         Show a description of a package.
        Read Help For A Package…    Opens the documentation for a package.
        Uninstall Some Packages…    Uninstall one or more packages.
        Internet Updates->          To download packages from Internet.
        Rebuild Package Indices     The Alpha's index of all installed
                                    packages.

    Mode Prefs              Set preferences for current mode.
        Menus and Features… Change current mode's menus and features.
        Preferences…        Change options for current mode.
        Edit Prefs File     Edit mode-specific preferences.  Loaded
                            after mode entered for the first time.
        Load Prefs File     Load current mode's preferences.
        Describe mode       Describe current mode's variable settings and
                            bindings.
        Change Mode…        Change the current mode.

    Set Font Tabs…          Change font and/or tabs for current file.
    Special Keys…           Set key bindings for electric features.
    Describe Binding…       Wait for a keystroke, then display that keystroke's
    List Packages           List all installed packages.
    List All Bindings       List all current key bindings.
    List Global Bindings (option) List all current global key bindings.
    List Functions          List all functions currently defined, both
                            "core" functions (those coded in C), and those
                            coded in the supplied Tcl files.
    View Saved Settings…    Any variables or flags that you modify during
                            the course of a session are saved to files in the
                            system preferences folder when Alpha quits.
                            This function shows all such saved variables.
    Remove Saved Settings…  This function allows settings to be removed.

    Redefine Colors->       See Coloring.

Windows (an icon with three windows)
    Zoom                    Zoom windows in and out.
    Default Size (option)   Resize window to default size.
    Choose A Window         Choose window to select from list (proc
                            chooseAWindow).
    Iconify                 Toggle iconification of front window.
    Arrange->               Rearrange open windows.

    Split Window            Split window into two panes, or unsplit.
    Toggle Scrollbar        Toggle the horizontal scrollbar on the frontmost
                            window.

        Installing New Packages

Where to find new packages

Currently the best place to look for new packages is
<ftp://ftp.ucsd.edu/pub/alpha/>.
For those from Europe, you may wish to try the mirror:
<ftp://anu.theologie.uni-halle.de/comp/mac/Alpha>

Using the menu "Config->Packages->Internet Updates" Alpha can download and
automatically install packages for you.

[to be continued]

What is already installed?

It is obviously a waste of time to install something which is already
installed or - worse - to install an old package replacing a more recent
version. The menu item "Config->List Packages" lists all packages which are
installed. The list contains the package names, versions, and maintainers.

If there is no read me file accompanying the package you are about to
install, you can find the version number in the beginning of the tcl file.
Look for a line of one of the forms:
alpha::extension <name> <version> ...
alpha::menu <name> <version> ...
alpha::mode <name> <version> ...
Make a sure the number given by <version> is higher than the one for the
currently installed package.

Installing

How to start the installation depends on if the package you are about to
install is accompanied by a file 'READ ME TO INSTALL' (or similar) or is
just a single file someName.tcl.
• If there is a file 'READ ME TO INSTALL', open it (hence the name!). All
packages built up of more than one file must actually have such a read me
file in order to be possible to install. If there is a file
installScript.tcl (or similar), don't open it. It only contains
instructions to Alpha what to install.
• If there is only a single file someName.tcl, open it. Some single file
package are configured to automatically close themselves and open a
installation dialog. Otherwise proceed as below.

If there are instructions in the read me file how to install the package,
follow them (of course!). In other cases this is how a typical installation
is made.
• After you have open the read me file or the single someName.tcl, make
sure Alpha has inserted a menu 'Install' in the menu bar. This means Alpha
is in installation mode. If not, you can manually switch to installation
mode by selecting 'Inst' in the mode popup menu in the statusbar.
• Select 'Install This Package' from the Install menu.
• An installation dialog is now opened. Here you can choose to make an Easy
Install or a Custom Install. The Custom Install lets you choose exactly
what to install. The Easy Install installs everything. If you are not sure
which files you need use the Easy Install.
• There are also two options in the installation dialog.
If 'Backup removed files' is checked Alpha will save any removed file in a
folder InstallationBackup in Alpha's folder. This as a safety measure so
you can recover any changes you may have made to them or so you can switch
back to them if the newly installed package doesn't work as you wish.
If 'Show installation log' is checked a window is opened after
installation showing which files have been put where and which files have
been deleted.

After Alpha has put the files in there correct location Alpha rebuilds its
index files. This make take a little while. The index files are used by
Alpha to keep track of where the various packages and function are.

After the installation is completed you must quit and restart Alpha.

If something goes wrong

What to do if you're unlucky and have installed a package which simply
doesn't work, possibly crashing Alpha when it's launched? The obvious thing
is then to uninstall the package. If Alpha can be launched with the new
package installed you can uninstalling it using the method in the next
section.

If the newly installed package causes Alpha to crash when you launch it,
the situation is more problematic. Then you have to manually delete some
files to make Alpha run again. First delete the files you've just
installed. During the installation the package's files are copied to
various locations in the folder "Tcl" inside Alpha's folder. Locate and
delete the ones with the same names as the ones in the set of files you
installed. Then before you launch Alpha again you have to delete a folder
from Alpha's preferences folder. Alpha's preferences folder is called
"Alpha-v7" and is located in the Preferences folder in the system folder.
Delete the folder "Cache" inside "Alpha-v7". Deleting the folder "Cache" is
harmless. It will be re-created the next time you launch Alpha. It is very
likely, though, that the old content was causing Alpha to crash.

If this doesn't help, as a last way out try removing the complete
"Alpha-v7" from the Preferences folder.


        Uninstalling Packages

Many packages support a mechanism for uninstalling them. Please note before
starting to uninstall packages you think you won't ever need that the only
thing you save by uninstalling a package is disk space - unless you have
installed some buggy package causing obvious problems. Installed packages
which are not in use, i.e. either not enabled through the dialog 'Menus and
Features' or modes which are not used, are never loaded into Alpha's
memory. Thus you do not save any memory by uninstalling packages. Thus if
you have plenty of disk space, there is hardly any point in uninstalling
anything.

Uninstalling a package in done using the menu item
"Config->Packages->Uninstall Some Packages". Select the package you want to
uninstall from the popup menu in the dialog. All files belonging to the
package are now permanently deleted. Only a reinstallation will restore the
package.

After the uninstallation you must restart Alpha.

If you can't find the package you want to uninstall in the popup menu, it
means that the package doesn't support the mechanism for automatic
uninstallation. In this case the only way uninstall the package is to
manually find the files belonging to the package and delete them. Don't use
this method unless you know what you are doing. Deleting the wrong files
may result in all sorts of troubles.

        Changing Alpha's behavior

The rest of the manual discusses some general topics about how to extend
Alpha by writing your own Tcl code.

First of all, where do you put your own Tcl code so that Alpha can find it?
Alpha has a set of preferences files for this purpose. There is one global
preferences file which is loaded when Alpha is launched. In this file you
should put code which should be loaded regardless of which mode you're
working in. This preferences file is opened using the menu item
"Config->Preferences->Edit Prefs File".

Then there is one preferences file for each mode. The file for a mode is
loaded after as the last code to be loaded when a mode is used the first
time. This preferences file is opened using the menu item "Config->Mode
Prefs->Edit Prefs File".

These preferences files are intended for code for personal use. If you want
to write a complete new package for Alpha, which others also can use, read
the file Extending Alpha.

        ALPHA-D mailing list

There is mailing list for Alpha where you can discuss problems, suggest new
features etc. To subscribe, email <[e-mail]> and, in the
body of your message (not the subject line), write:
SUBSCRIBE ALPHA-D

There are a number of known bugs which will hopefully be corrected in a
future release. PLEASE read the Bug Reports and Debugging file for a list
of known bugs, and for how to give an informative bug report, without which
it is unlikely any bug you found can be fixed.

        Key bindings

Any Tcl command can be bound to any single keystroke. One way to bind a
function is with a statement such as:

      Bind 'c' <modifier string> funcName [<mode>]

where c is a character, <modifier string> is an optional string containing
one or more of:

      c   - command modifier
      o   - option modifier
      s   - shift modifier
      z   - control modifier
      e   - escape modifier

'mode' is an optional parameter that specifies, when present, that the
binding is only active in a given mode. Note that given a general binding
(no mode specification) and a binding specific to the current mode, the
last binding to have been created is the one found first.

For example, the following line binds cmd-shift-f to the function
'forwardChar':

    Bind 'f' <cs> forwardChar

Additionally, the modifier string can contain a capital letter specifying
that the binding is only activated if preceded by control and the lowercase
version of that letter. This feature allows multiple-key combinations a la
Emacs. This requires that ctrl-<the character> is bound to the function
'prefixChar'. By default ctrl-C, ctrl-Q, and ctrl-X are bound to
'prefixChar'. The next line would bind 'forwardChar' to ctrl-x ctrl-f:

    Bind 'f' <cX> forwardChar

Additionally, most keyboards have keypads and/or function keys. These
keys can be bound using case-insensitive numeric labels using the same
bind command as above, with the label replacing the character. For
example, to bind F1 to function 'funcName', the following would work:

    Bind F1 funcName

As above, the binding can include a modifier string. The following labels
are defined:

  Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 Help Home Pgup Del
  End Pgdn Left Right Up Down Clear Kpad0 Kpad1 Kpad2 Kpad3 Kpad4 Kpad5
  Kpad6 Kpad7 Kpad8 Kpad9 Kpad= Kpad/ Kpad* Kpad- Kpad+ Enter Kpad.

The above labels may not be sufficient for all keyboards (attention
international users). In particular there are some problems when binding to
accented characters (more about that below). If a hex number is used
instead of a character inside the single quotes, the binding is done to key
codes instead of ascii values. The following is a key code version of the
same binding:

    Bind 0x03 <cs> forwardChar

The key code for any given key can be obtained by selecting the menu item
"Utils->Ascii Etc->Key Code" and then typing the key. Alpha then types the
key code.

Also, there is an alternate form that allows the specification of an
ascii code directly:

    ascii 0x20 <z> setMark

Binds control-space to 'setMark'. The ascii code for any given key can be
obtained by selecting the menu item "Utils->Ascii Etc->Key Ascii" and then
typing the key. Alpha then types the ascii code.

Note that menu item command equivalents take precedence over bindings, and
that the 'Bind' command does not affect the command equivalents displayed
in the menus. Also note that key code bindings take precedence over ascii
bindings.

Finally, there are 'unBind' and 'unascii' functions, with identical
arguments to their counterparts.

Bindings to accented characters

To bind to an accented character is not always as straight forward as
binding to an un-accented one.

Accented characters which can be typed directly without using a dead key,
you can bind to them as long as they have a modifier different from <s>. As
an example with a French keyboard

    Bind 'é' <c> ...
    Bind 'é' <z> ...

works fine, but

    Bind 'é' ...
    Bind 'é' <s> ...

does not. In the latter case the key code has to be used instead:

    Bind 0x13 ...
    Bind 0x13 <s> ...

Accented characters which are obtained using a dead key has to be bound
using ascii, e.g 'ì' on a French keyboard:

    ascii 0x93 ...

What to bind to?

When you want to define a new key binding you obviously want to use a key
combination which is not already in use. There are two different ways to
find if a key combination is free.

First, the menu item "Config->List All Bindings" will list all of the
bindings currently in effect.

Second, you can use "Config->Describe Binding" to find what a certain key
combination is bound to. Select "Config->Describe Binding" and then hit the
key combination you are interested in. Alpha will then display a dialog
saying which function the key combination is bound to, or "Key combination
unbound." if it is not bound to anything.

There is one thing to note about bindings involving the shift key. If there
is nothing bound to a key combination including the shift key, typing this
key combination will have the same effect as the one wihout the shift key.
A specific example to clarify this: command-P is bound to "print", but
there is no binding defined for command-shift-P. Still hitting
command-shift-P has the same effect as hitting command-P. But if you now
define a new binding for command-shift-P, then command-P and
command-shift-P will have different functionality.

        Menus, user-defined

If you want to make your own menu with your personal Tcl functions, this
section explains how to do it. If you want to add new menu items to the
existing menus, see the next section for instructions. However, in that
case you also need to read this section.

Alpha's menu commands allow the user to build custom menus which contain
names of functions, macros, or arbitrary TCL commands that just HAVE to be
in the menus, as opposed to being merely callable through the bindings. The
menu items are defined as a list of strings. The following meta characters
can be embedded in the strings:

   Meta-character     Usage
   --------------     -----

    ; or Return       Separates multiple items.
    ^                 Followed by an icon number, adds
                      that icon to the item.
    !                 Followed by a character, marks the
                      item with that character.
    <                 Followed by B, I, U, O, E, or S,
                      sets the character style of the item.
    /                 Followed by a character, sets up
                      a keyboard equivalent.
    (                 Disables the item. Use (- to get a
                      separator line.

The following modifiers can be used to require other combinations of
modifiers than just the command key. Control-option, for instance, is
specified by putting the string "<B<I" in the menu item. The menu symbol
for shift is an upward outline arrow, control is the outlined ^ symbol
("Wins->Iconify" has one), and option is the wavy line with the dot in the
upper right ("Search->Replace All" has one). The following are characters
that can follow the '<' and what they signify.

    B       - control key required
    I       - option key required
    U       - shift key required (only for alpha-numerics!)
    O       - command key required
    S       - is part of a dynamic item.
    E       - forces item to start new dynamic item.


A '/' followed by a character in the left column sets up a keyboard
equivalent for the key in the right column:

    a   Enter           n   F10
    b   Return          o   F11
    c   Tab             p   F12
    d   Num Lock        q   F13
    e   F1              r   F14
    f   F2              s   F15
    g   F3              t   Help
    h   F4              u   Del
    i   F5              v   Forward Del
    j   F6              w   Home
    k   F7              x   End
    l   F8              y   Page Up
    m   F9              z   Page Down

The menu creation syntax is :

    Menu [-s] <-n name> <-i num> [-p procName] [-m] [-M <mode>] "Tcl list of menu items"

Where the arguments have the followings meanings:
  -s            Use system menu definition proc (faster).
  -i <num>      Resource id of icon suite to use for menu title.
  -n <name>     Name of menu.
  -m            No menu form. If not supplied, each menu item is split into
                words at each capitalized letter.
  -p <pname>    Rather that having alpha call a Tcl proc named by the menu
                item's text, this option tells Alpha to call the tcl proc
                named by 'pname' with two arguments: the menu name, and the
                text of the menu item chosen.
  -M <mode>     Bindings only take effect in specified mode.

The 'Tcl list of menu items' can include another menu definition allowing
you to create hierarchical menus. Once the menus are created, they can be
inserted and deleted from the menu bar by the syntax:

   insertMenu "name"
   removeMenu "name"

As alluded to above, Alpha attempts to make procedure names readable in the
menus by separating words at any capitalized letter. For example,
'findFile' becomes "Find File". This function is turned off by the '-m'
option.

Menu items can be enabled and disabled through the TCL command
'enableMenuItem'. Menu items checkmarks can be turned on and off via
'markMenuItem'. Menu items can be appended via 'addMenuItem' and deleted
via 'deleteMenuItem'. See the "Alpha Commands" help file for syntax.

As explained above, Alpha uses various keys to specify text style and key
equivalents. Sometimes you may want these characters included in your text
literally. If an ampersand ('&') is the last character in a menu item,
these special characters are not interpreted.

If an ellipsis ('…') is the last character in a menu item (except possible
for the above ampersand), it is stripped off before searching for the
function corresponding to the chosen item.

        Modifying Alpha's menus

Alpha's global menus and most mode menus can be modified using commands
menu::insert, menu::removeFrom, and menu::replaceWith. The use of these are
explained in the section Adding items to global menus in the file Extending
Alpha.

        Event hooks

When certain events occur. e.g. when opening and closing windows, Alpha
calls an event hook. You can register your own event hooks to add to the
default behavior when the corresponding event occurs. Below is a table of
all available hooks.

To add your own hook there are two things you have to do. First write a
proc to be called when some events occurs. This proc must have the
parameters shown in the table. Lets say you want to define a saveHook.
Then define some proc

    proc mysaveHook {name}{
        .
        .
    }

The next thing you have to do is to register the proc. This is done with a
line like:

    hook::register 'hook-name' 'your proc' 'mode' ?... 'mode'?

The optional mode parameters specify in which modes the hook will be
called. If no mode parameters are given the hook will be called regardless
of the mode. Avoid this unless absolutely necessary.

Let's assume that you want your hook to be called in TeX and Perl modes.
To register it you would use the line:

    hook::register saveHook mysaveHook TeX Perl

Note, however, that a few hooks doesn't use the mode to determine when to
be called and should be registered slightly differently, see below.

Window hooks
  Hook                                              Parameter(s)
• activateHook                                      path to file
  Called when a window is brought to front
• deactivateHook                                    path to file
  Called when a window is sent to back
• openHook                                          path to file
  Called when a window is opened
• closeHook                                         path to file
  Called when a window is closed
• saveHook                                          path to file
  Called when a window is saved
• saveasHook                                        path to old file, path to new file
  Called when a window is saved as
• savePostHook                                      path to file
  Called after a window is saved

Alpha hooks
  Hook                                              Parameter(s)
• startupHook
  Called at the end of startup
• quitHook
  Called when quitting Alpha
• suspendHook                                       an empty string
  Called when switching to another app
• resumeHook                                        an empty string
  Called when switching to Alpha from another app

Mode hooks
  Hook                                              Parameter(s)
• mode::init
  Called the first time a mode is loaded
• changeMode                                        new mode
  Called when the mode is changed
• dialog::modifyModeFlags                           a string (title of dialog)
  Called after a mode prefs dialog is closed
• mode::editPrefsFile
  Called when a mode prefs file is opened
  for editing

Keyboard hooks
  Hook                                              Parameter(s)
• keyboard
  Called at startup and when the keyboard prefs
  is changed
• removekeyboard
  Called when the keyboard prefs is changed

The keyboard hooks use the keyboard name (the ones in the keyboard popup menu
in the International preferences dialog) rather than the mode to determine
when to be called. Thus to register a keyboard or removekeyboard hook use
lines like:

    hook::register 'hook-name' 'your proc' 'keyboard name' ?... 'keyboard name'?

Miscellaneous hooks
  Hook
• launch
  Called when a helper app is launched by calling app::ensureRunning

The launch hook uses the application signature rather than the mode to
determine when to be called. Thus to register a launch hook use a line like:

    hook::register launch 'your proc' 'signature' ?... 'signature'?

• requireOpenWindowsHook
  Called when opening and closing windows.

This hook is used to en-/disable meaningless menu items which would require
the presence of a certain number of windows to be active. You can register
your own menu items using a line like:

    hook::register requireOpenWindowsHook [list menu item] N

where 'N' is the number of windows required (1 or 2 usually)

As an example, this is a line from Diff mode registering the item 'Compare
Windows' to require 2 open windows to be enabled.

    hook::register requireOpenWindowsHook [list compare windows] 2

        modeCreator

The modeCreator array allow you to tell Alpha which mode to choose when you
open a window depending on which application has created the file. Add to
this array with lines like:

    set modeCreator(<signature>) <mode>

'Signature' is the signature of the application which has created the file
and 'mode' is the mode which you want Alpha set for the window. For
example, to open all files created by Netscape in HTML mode use the line:

    set modeCreator(MOSS) HTML

Tip: To find the signature of an application, launch it, open the Tcl
shell (command-Y) and type 'ps' at the prompt. This will list all running
applications; the second column lists the signatures.

        unixMode

When you open unix files where the first non-empty line reads
'#!/dir/subdir/command ...' then Alpha tries to find a mode corresponding to
'command'. With the unixMode array you can tell Alpha which mode to choose
when opening such a file. Add to this array with lines like:

    set unixMode(<command>) <mode>

where 'command' is the command in the line '#!/dir/subdir/command ...' and
'mode' is the mode which you want Alpha set for the window. For example, to
make Alpha open files with a line '#!/dir/subdir/perl ...' in Perl mode use
the line:

    set unixMode(perl) Perl

        Word breaking

Alpha allows you to redefine its internal notion of what a word is, through
the preferences 'Word Break', and 'Word Break Preface'. 'Word Break' is set
to a regular expression that defines a word to you. 'Word Break Preface'
should be a regular expression that matches exactly one of any characters
that are not in your word definition.

The value of 'Word Break' and 'Word Break Preface' are mode dependent, as
what is meant by a word may be different for different types of text. For
example, in Text mode the default definition of 'Word Break' is '\w+'. This
matches any contiguous sequence of contiguous alphanumeric characters.

The default value in Text mode for 'Word Break Preface' is '(\W)',
basically just the negation of any any of the characters in your 'Word
Break' definition.

The need for both these variables in backward searches can be seen as
follows. Suppose your window's text is 'hey hello', and the current
insertion is between the two 'l's. Now, searching backwards for the above
'Word Break' definition will take the insertion to between the 'e' and the
first 'l', not really where we want to say is the start of the word. By
contrast, if we search backwards for 'Word Break Preface' and 'Word Break'
concatenated together, and then move forward one character after a
successful search, we end up right before the 'h' in 'hello', just where we
want to be.

There are also two similar preferences 'Wrap Break' and 'Wrap Break
Preface' used for automatic word wrapping. In Text mode their default
values are '[\w_]+' and '([^\w_])' meaning that wrapping should not occur
between alphanumeric characters or underscore.